Summary

This PR introduces support for nested sub-WHERE clauses in query methods and standardizes hook naming to align with the StellarWP namespace. These changes enable more flexible and complex database queries while maintaining backward compatibility through semantic versioning.

Key Changes

1. Nested Sub-WHERE Clauses - Adds the ability to build complex queries with grouped conditions and custom operators (AND/OR) within the paginate() and get_total_items() methods.

2. Hook Naming Standardization - Renamed all hooks from tec_common_* prefix to stellarwp_schema_* prefix for namespace consistency (breaking change, documented in CHANGELOG).

Technical Details

Sub-WHERE Clause Implementation

The implementation extracts sub-where clause logic into a new private method build_sub_wheres_from_args() that recursively builds grouped query conditions. This allows developers to construct queries like:

// Query: WHERE (type = 'classic' OR type = 'premium') AND price_cents < 1500
$results = Model::paginate([
    [
        'query_operator' => 'OR',
        [
            'column' => 'type',
            'value' => 'classic',
            'operator' => '=',
        ],
        [
            'column' => 'type',
            'value' => 'premium',
            'operator' => '=',
        ],
    ],
    [
        'column' => 'price_cents',
        'value' => 1500,
        'operator' => '<',
    ],
], 20, 1);

Architecture Decision: The recursive approach allows for arbitrary nesting depth without code duplication. Each sub-where group is wrapped in parentheses and joined with its specified operator, maintaining SQL precedence rules.

Breaking Changes

Hook names have been changed to reflect the correct namespace:

• tec_common_custom_table_query_pre_results → stellarwp_schema_custom_table_query_pre_results
• tec_common_custom_table_query_post_results → stellarwp_schema_custom_table_query_post_results
• tec_common_custom_table_query_results → stellarwp_schema_custom_table_query_results
• tec_common_custom_table_query_where → stellarwp_schema_custom_table_query_where

Migration Path: Consumers using these hooks must update their code. The change is documented in CHANGELOG.md with clear before/after examples.

Documentation

Updated documentation includes:

• CHANGELOG.md: Comprehensive entry for v3.2.0 with feature description and breaking changes
• docs/query-methods.md: Extended with sub-WHERE clause examples and updated hook references

Areas Requiring Review Attention

1. Recursive Logic: Verify the recursive sub-where building logic handles edge cases correctly
2. SQL Injection: Confirm that the prepared statement handling remains secure with nested conditions
3. Breaking Changes: Validate that the hook renaming is properly documented for consumers
4. Test Coverage: Review test cases for completeness, particularly around operator precedence